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Product Overview 


Provide more reliable, secure and private access to the internet by crowdsourcing the provision of 
P2P proxy-servers directly from the web-browser. 


Goals 
e Give access in a way that is hard to block: blocking is always possible, but we can push up the 
collateral damage so that to block uProxy as much of the rest of the internet has to be blocked 
(e.g. assuming that no country will not block all social/chat networks, video conferencing, and 
email). 
e Improve security and trust: provide a better basis for the both users and providers of proxies to 
trust each other and have the capacity to securely communicate. 


e Useful to users: provide a reasonably fast proxy service that can be widely used. 


Non-goals 
e Strong anonymity. We are not trying to anonymize the proxy owner and user from each other. 
uProxy depends on leveraging existing trust relationships to to find and use a proxy. 


Strategy: Make it easy to: 
e Setup a proxy server for selected friends to use, and 


e Connect to a proxy provided by your friends. 


Implementation: a browser extension, initially for Chrome and Firefox, that makes it easy for users to 
setup and access peer-to-peer proxy-servers using an obfuscated version of WebRTC's data-channels. 


See uProxy product overview. 


User Interface Mocks 
For the full set of mocks, see the UI/UX prototype mocks. 
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Technical Design Objectives 


1. Robust to interference: 
a. Minimise single points of failure 
b. Supports obfuscation of proxy connections 
c. Easily extended/strengthened in light of attempts to block or surveille usage 
2. Scaleable: the more users the more proxies. 
3. Performant: Performance of proxying should not be (orders of magnitude) slower than normal 
internet connection; ideally it should be faster. 
4. Private: Provide good level of privacy for both the uProxy client and uProxy server 
a. Maintain end-to-end encryption of https 
b. Minimise risks of surveillance and MITM attacks 
c. Minimise finger-printability of uProxy usage 
d. Minimise any personal information observable from usage 
5. Usable: Minimize user-effort needed to setup a proxy, and to access a proxy provided by a 
contact. 
6. Incentives: Maximise incentives for users / mitigate the legal disincentives 


Note: there are inherent tradeoffs here; the technical and product solution is intended to hit a sweet spot 
and give a reasonable solution to all of the above. 


Overview of uProxy Architecture 
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Platform (Chrome/FF/node) 


uProxy consists to two top-level components: 


uProxyUI: this holds the uProxy controllers and provides a UI by which actions are sent to the 
uProxy Core. The UI allows a user to control their profile, the social networks they are connected 
to, view the roster of contacts, control proxy consent for a particular contract, and do ZRTP-style 
video/audio-authentication. 

uProxyCore: this actually runs uProxy and consists of a state that holds all the contacts, the 
current networking state, consent for each contact etc. It also runs web-workers to manage 
connections to the social network, as well as transport providers that are used to give or get 
access. 


To allow the uProxyCore to run on different platforms and to allow components to be swapped out easily, 
we have a platform independent library (called Freedom) for: 


Sockets (UDP and TCP). 

Social networks (XMPP, WebSockets, copy/paste), including controlled authentication views, e.g. 
to use G+ sign-in authentication in the browser. 

P2P transport (a wrapper for WebRTC that uses data channel labels and does chunking to get 
around WebRTC's chunk-limit). 

Storage (For browsers, this is local storage, for node we can swap it out for another form of 
storage). 

Obfuscation (Stateful Array buffer manipulation; designs: DTLS header-hiding design; Rabbit 
stream cypher). 


uProxy contacts are instance based: each instance of uProxy is a different contact. Each instance has its 
own description and offering or requesting access is done on a per-instance basis. 


Components involved in P2P proxying 
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The UI allows the user to select a contact to proxy through. When the user clicks to start proxying 
through a contact, the extension notifies the core, and the core sets the state to "starting to 
proxy". The UI provides an indication to the user that proxying is being setup. 
o We assume that uProxyCore has already checked permissions and sent a message over 
the (assumed to be high latency, low bandwidth) social/signaling channel to indicate to a 
peer that it would like to start proxying. The server checks the client has been given 
access. 
The server and client both start setting up the peer-to-peer connection by pinging stun-servers to 
create a hole (association between public and internal ports) on their local NAT firewall. The 
STUN also allow the clients to identify the public facing IP addresses. 
SDP headers are exchanged to tell the server and client each other's public facing IP/PORT and 
ICE protocol is used within WebRTC to select a candidate. 
The server's browser lets the user know that a proxy session for a peer is being setup. 
uProxyCore opens a socket on localhost that acts the receiving end of a SOCKS5 proxy. 
o The browser's proxy settings are set to the relevant localhost:port. 
o The UI changes the BrowserAction icon to indicate that the browser's traffic is now going 
through a uproxy-connection (and whatever other UI we feel we need to set) 
A peer-to-peer WebRTC peer-connection is created to allow web traffic to be proxied P2P 
between the two browsers. 
o Web requests made by the browser now go through the localhost proxy; WebRTC also 
go through the localhost proxy to allow obfuscation. 


7. Traffic is now sent from the client device to the localhost proxy to the peer to the final website and 
back again. 


In more detail, for the proxy-client-side (getting access), the networking pathway is as follows: 
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Chrome running on the client device sends web-requests to the localhost socks5 proxy. 
The localhost socks5 proxy translates the request into a JSON message over a JS requested 
data channel. 

o Chrome creates the data channel. This involves UDP socket that is proxied to the localhost 
socksd proxy. 

o The localhost socks5 proxy receives the UDP traffic, obfuscates it, and sends it directly to the 
peer. 

o The peer receives the UDP traffic on a uProxy-core-created UDP socket which is acting as a 
UDP proxy for Chrome. 


And for the proxy-server-side it looks like this: 
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uProxyUI (Front-end) 


Polymer is used to implement MVC style with robust data binding, and independent reusable 
components." 


Internationalization is implemented by inheriting the language environment from the browser and using 
<dbi> tags to control flow. By separating textual chunks from variables using <span> tags we can control 
RTL and LTR flow. To lookup i18n strings for textual content we use i18n_template.js. 


A browser-action provides the web-browser with an Icon the user can click on, as well as which can show 
the user notifications. e.g. the user is currently proxying through a contact, or a contact is proxying 
through the user. 


When the remote proxy server stops for some reason, it is important to show the user a notification and 
require a user action before undoing the localhost proxy settings - so the user is conscious of the fact that 
their search is no longer being proxied. 


e In Chrome: We do this by opening a chrome-extension html page, and having the page 
communicate with the extension via chrome chrome.runtime message passing. 


Fore more details, see the uProxy front-end design doc. 


uProxyCore (Back-end) 


Core data structures 


1 (We tried Angular JS first, but it has some 'unfixable' bugs when used in Chrome extensions that get dynamic data input from 
Chrome Apps) 


There is a global variable for the social networks. This is a map from a social network name, e.g. google, 
to a user-ids and their mapping to the actual data structure for that network. 


Each social network has the user's local instance information (description, keys, etc) and a roster of all 
contacts. The roster is a map from the remote user's id to the remote user information. 


Each remote user information consists of the instances for the remote user. Each instance corresponds to 
a an installation of uProxy. For each remote instance, there is a consent structure that defines whether 
the remote instance is allowed to use this installation as a proxy server. See the consent section for more 
details. 


Freedom & Module Isolation 


We isolate components using the Freedom Library. This runs modules in WebWorkers and provides 
RPCs for those web-workers to call functions in the core javascript runtime environment. For example, an 
XMPP social network client will run a web-worker and has access to sockets only by message-passing in 
a restricted way to the freedom core environment. Using Freedom isolates state, makes uProxy more 
robust to module crashes, and allows certain components to be swapped out while limiting the 
interactions they can have with the rest of the system. Freedom uses transferable objects to move larger 
amounts of data between runtime environments. e.g. ArrayBuffers containing the web-resources being 
proxied. 


Social providers 


The social abstraction 


Our abstraction of a social network has a fixed user-id for each user which can be connected to the 
network via a number of different clients. Each client has a unique ephemeral client-id; the client-id is 
different every time you login. The social network provides a signalling channel such that, at a relatively 
high latency and low bandwidth (often throttled) messages can be exchanged between users' instances 
of uProxy. The signalling channel is used to send information about the instance of uProxy that includes: 
e Identifiers for instances along with key-information (used for obfuscation, and checking 
authenticity of messages) and the consent status between users' instances of uProxy (who can 
proxy through who). 
e Information used to setup a P2P connection that traverses NAT firewalls (typically SDP headers, 
and the P2P connection candidates). 


More details on signalling messages are in the uProxy signalling message design doc. 


Authentication with social networks 


See the uProxy OAuth Design Doc. We open a tab, use standard OAuth, but set the redirect URL to a 
uproxy.org domain URL, but then handle the URL request locally using URL handler APIs. This way no 
redirect URL request is sent on the wire, and we can get the token directly within uProxy. For 
Authentication with Google, we use the AddUser URL as this allows selection between multiple google 
accounts. 


Peer-authentication / Instance Consent 


Consent to act as a proxy or to access a proxy is controlled according to the uProxy Consent Design. In 
particular, each user has a boolean for each other user to express whether the other user is allowed to 
proxy through them. This boolean is called the bit for consent to be a proxy server for the remote user. 
This is checked when a signalling message is received that indicates the remote user wants to start being 
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a proxy client (sent within instance signalling messages). To allow a user to control which other users 
appear in the list of contacts they may want to proxy through, there is a second bit called the consent to 
be a proxy client. 


We refer to an install of uProxy as a uProxy Instance. All consent state is instance-specific. In particular, 
each instance has it's own instance-identifier which are global and unique (they are essentially large 
strings chosen at random - potentially public-key hashes). An install of uProxy should have a different 
instance-id for each user-id in its social provider. This avoids leaking that the user-ids for two networks 
are in fact owned by the uProxy instance. 


TNetworking 


WebRtc Transport 


uProxy's transport is intended to make it (relatively) easy to swap out WebRTC P2P communication with 
another mechanism of communication with the proxy server. Similarly, wnen WebRTC is used, we want to 
make the form of network traffic obfuscation easy to pluggable. For v1 we have not specified a protocol to 
choose the form of transport and WebRTC is currently hard-wired. For later versions we plan to make 
Transport a pluggable component that is negotiated between the peers. 


The SocksToRtc.Session and RtcToNet .Session classes are written in terms of an abstraction 
(peerconnection) of the WebRTC API that is intended to capture the minimal requirements needed for a 
form of transport that can proxy tcp connections and which may need to exchange some signalling 
messages with the end-point it is planning to proxy with. For WebRTC, the signalling messages contain 
the public facing port and IP needed to establish the P2P connection. The PeerConnection API abstracts 
over the content of signalling messages (it assumes that it has been wired to send such messages to a 
compatible end-point). In the case of WebRTC, PeerConnection deals with creating SDP offers, answers, 
handling locally found ICE candidates as well as remote ones received over the signalling channel, as 
well as buffering data to be sent and opening and closing data channels for each request. 


Socks-to-Rtc 


socks-to-rtc creates a localhost socks5 proxy and route requests those requests over a WebRTC 
transport. Each TCP-based socks5 request results in a new data channel for that request. The data 
channel and corresponding tcp request are managed by the SocksToRtc.Session class which is 
responsible for: 

e The socks-protocol handshake management 

e Sending and buffering data between the data channel and the tcp connection 

e Closing the socks5 tcp request when the data channel closes, as well as closing the data channel 

when the client closes the tcp connection to the socks5. 


Rtc-to-Net 


rtc-to-net listens for requests on a WebRTC transport and for each request it opens a TCP request to the 
destination. Similarly to the socks-to-rtc module, each data channel represent a TCP request and there is 
a RtcToNet.Session class which manages the relationship between a data channel and it's TCP 
connection. 


Churn 


The uProxy churn module provides an implementation of PeerConnection that uses an obfuscated 
WebRTC session with a pluggable packet-level obfuscator. Various implementations of packet-level 


obfuscation are provided by the uproxy-obfuscators repository. The design of Churn is quite involved; the 
following two documents describe our past and current approaches: 


e original Churn Design Document 
e Holographic ICE (implementation, as of June 2016) 


uProxy on different platforms 


uProxy is designed so that it can be deployed in different runtime environments. E.g. Firefox, Chrome, 
Node (for headless uProxy), etc. This is done by using Freedom's cross-platform implementation (in 
freedom-for-firefox, freedom-for-chrome, and freedom-for-node) of the common core libraries that we use 
(in particular, for sockets and storage). 


uProxy for Chrome 


uProxy for Chrome consists of two installed Chrome components: 
e uProxy Chrome Extension: implements the uProxy UI 
e uProxy Chrome (Packaged) App: implements the uProxy Core 
The two components speak to each other using Chrome's message passing API. 


The diagram below shows the Chrome APIs used to implement uProxyUI and uProxyCore. Note that only 
chrome extensions are allowed to set the proxy settings, and only Chrome Apps are allowed raw socket 
access. This forces us to have both a Chrome extension and a Chrome App?. 


? The need for both a chrome extension and a chrome app will be revisited in the future. The problem is that Chrome apps cannot 
set proxy settings, cannot manipulate tabs, and don't allow a button in the chrome-bar for user-interaction. On the other hand, 
Chrome extensions cannot access raw sockets. So we need both a Chrome App and a Chrome Extension, or uProxy needs to be 
whitelisted and changes to the APIs are needed to allow uProxy to access both sets of APIs. 
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; Extension UI App Ul 
UProxy UI UProxy Core 
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XMPP WebRTC 
Messaging 
API 
WebRTC API 
Proxy API Local Storage Sockets API 


API Data Channels 


SCTP/DTLS/UDP 


Operating System 


The manifest.json file for the Chrome App app will need the permissions for raw sockets and for local 
storage. To exchange auth-codes for auth-tokens we also need to send HTTP requests to the oauth 


domains for social networks that uProxy speaks to. 


"socket": ["tcp-connect", "udp-send-to", "udp-bind", "tcp-listen"]}, 
"storage", // for storage of profile/contacts & their keys. 


// + URLS for each social provider we need to connect to for authentication, e.g. 
"https: //accounts. google.com/*" 


The manifest.json file for the Chrome Extension provides: 
e abrowser action that shows the popup for the main Ul 
e abackground page that manages communication with the Chrome App that runs the uProxyCore. 
e anoptions page with additional advanced settings and debugging information. 


"“videoCapture", // for ZRTP-style auth 
"audioCapture", // for ZRTP-style auth 
"tabs", // for our authentication flow 


"proxy", // to set Chrome's proxy settings 
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uProxy for Firefox 


In firefox, the uProxyUI and uProxyCore live in the same uProxy add-on. UI part runs in 


live in the same runtime environment, so we simply remove the stubs and allow direct JS calls from UI to 
Core. 
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Storage 
SCTP/DTLS/UDP API 


Operating System 


uProxy for Node 


[WARNING: early stage thinking] Details of the efforts on uProxy for cloud, which is intended to allow 
uProxy to run in a node environment on the cloud are documented in the uProxy for cloud design doc. 


uProxy for Android 


[WARNING: early stage thinking] See uProxy for Android doc: we plan to use Cordova to provide a 
standalone ChromeApp in Android that lets the user have both a web-browser view and a contact list. 
This app will be a VPN service which allows it to either act as a simple proxy for only its connection, only 
Chrome's, or a as a proxy for the whole device. 
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P2P security 


WebRTC includes verification of the certificates by their hashes which are sent through the signalling 
channel. In addition, to allow use of non-trusted social networks, we will provide ZRTP-style video 
authentication (See mocks). 


XFF headers 


By default, to meet users expectations (and it helps avoid honey pot attacks) XFF headers are not used. 
They can always be spoofed anyway, so they are not good to rely on and they would give a strong signal 
of a user using uProxy (most internet traffic doesn't have XFF), so it would be bad for users of uProxy to 
include them. 


Measuring usage 


At present the only data we plan to know are the download stats from the Chrome Webstore. 

e Weare considering how to measure uproxy usage in further details for v2. We may ask users if 
we can collect high level usage stats for the people they provide a proxy to. If we do this, and the 
user agrees, then the uproxy server will send summary stats: number of users & bytes transferred 
for them rounded to nearest 10k. This would have to be transferred by one end of the proxy to 
some server we operate. The problem is that for some cases (server's in repressive 
environments) this would give away who is using uproxy. 

e We considered using a landing page for when uProxy successfully establishes a P2P connection. 
But proxying into repressive environments would then give away users of uProxy. This could be 
mitigated by an opt-in. 

e Chrome has some anonymising statistic gathering. TODO: investigate how this works and if we 
can use it. 


Localization 


Many parts of the uProxy UI are generic to the platform. We use a custom data-store that can translate to 
Firefox, Chrome, or another localization environment. More in the uProxy UI Localization doc. 


Appendix 


Threat Analysis 
There are many ways that uProxy might be attacked. See the uProxy Threat Analysis Doc. 


Terminology 


Where possible, code is written in TyopeScript. This provides convenient typing that is easy to learn and 
lightweight in syntax. Interfaces make refactoring easier, makes tests cleaner and easier to understand, 
produces less code (less dynamic type-checking). It improves security and readability too. 
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Technologies 


Git / github.com open-source repository hosting; using Apache 2 license. 
NPM for dependency management/importing dependent JS projects (JS/node standard) 
Grunt as the build/task system (Standard for JS/CoffeeScript-based projects) 
JavaScript as TypeScript for type-checking + syntax improvements on JS 
freedom.js: a platform independent distributed programming on a web-platforms in JS. 
Jasmine for writing/running tests. 
Travis for continuous build/test status. 
Coveralls for coverage measurement. 
Bower for UI libraries (specified in common/ui/bower. json) 
Polymer for coding UI. 
Sass as better way to write CSS. 
WebRTC, part of HTML5. Provides web-based P2P communication. Used for P2P data channel 
for proxying and as basis for video/audio authentication in the ZRTP style. 
o DITLS is the low-level protocol for encryption of UDP used by WebRTC data channels. 
o SCTP is the reliability layer in WebRTC run on top of UDP. usrsctp is the standard 
implementation (used in Chrome and Firefox). 
o LibJingle: an open-source C++ library (and sample applications) that enables you to build 
a peer-to-peer application: uses DTLS/SCTP. It handles creating a network connection, 
NAT hole-punching, negotiating session details (codecs, formats, etc.), and exchanging 
data. 
SOCKS5 as a the protocol for running a local proxy. 
TURN/STUN and ICE - protocols used for NAT hole-punching. 
Chrome Apps and Chrome Extensions as implementation of uProxy for Chrome. 
o Chromium: Open source codebase for Chrome. 


o https://groups.google.com/a/chromium.org/forum/#!forum/chromium-apps - this is a public 
message board about chrome app development 


o https://groups.google.com/a/google.com/forum/#!forum/chrome-apps-discuss - this is the 
Google internal version in case we don't want to post our questions to the outside world. 
Firefox extension as implementation of uProxy for Firefox. 


Protocols 


RTP (Real-time Transport Protocol) 
o designed for end-to-end realtime media; provides jitter compensation, detection of out of 
sequence arrival, 
SRTP (Secure RTP) 
o provides encryption, message authentication and integrity. 
RTCP (Real-time Transport Control Protocol) 
o monitors RTP, statistics and QoS for RTP. 


SCTP (Stream Control Transmission Protocol) 
o Message-based, order of messages not guaranteed (but order within a message is), 
congestion control. 
DTLS (Datagram Transport Security Layer) 
o Used to provide encrypted communication over a UDP stream. 
UDP (User Datagram Protocol) 
o Unreliable (only checksums for data integrity), Fast (no delay for reliability), Stateless, 
stream of data organised into datagrams. Can send to multiple destinations from a single 
socket. 
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TCP (Transmission Control Protocol) 
o Reliable (error & loss free), stream-ordering, flow & congestion control, sockets go to a 
single target address. 


o Approach to creating P2P connections (includes getting around NAT restrictions). 

o Protocol/server used to create peer connections (part of ICE). 

o Asimple proxy service for the case when 2 NATs are restrictive NATs. Used as a fallback 
when incompatible NATs are encountered. Needed for approx 10% of NATs. Provided by 
various orgs. 


SOCKS 
o Aproxy protocol. SOCKS v5 supports UDP and TCP. 
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